Building and Hosting Your Risotto Documentation Site

Building Your Site

Running the Build Command

To generate your static documentation site, use the following command in your project directory:

Customizing the Build Process

You can customize the build process with the following parameters:

python3 risotto.py --docs my-docs

python3 risotto.py --config custom.config.risotto

python3 risotto.py --output build

What Happens During the Build

• All Markdown files in the specified docs directory are converted to HTML.
• The output directory is created if it doesn’t exist.
• Existing HTML files in the output directory are overwritten.

Previewing Your Site Locally

Using Python's Built-in Server

1. Navigate to your output directory:

1. Start a local server:

1. Open your browser and go to:

Using Other Local Servers

You can also use tools like serve, live-server, or any other static file server to preview your site.

Hosting Your Site

Static Hosting Platforms

Risotto generates static HTML files, so you can host your site on any platform that supports static websites. Here are some popular options:

Netlify

1. Drag and drop the output folder (e.g., site/) to Netlify’s dashboard.
2. Your site will be deployed immediately and provided with a unique URL.

Vercel

1. Install the Vercel CLI:

1. Deploy your site:

1. Follow the prompts to complete the deployment.

GitHub Pages

1. Push the contents of your output folder to a GitHub repository.
2. Go to the repository settings and enable GitHub Pages.
3. Select the branch and folder containing your site files.

GitLab Pages

1. Push the contents of your output folder to a GitLab repository.
2. Create a .gitlab-ci.yml file to configure the deployment.
3. GitLab will automatically build and deploy your site.

Surge

1. Install Surge:

1. Deploy your site:

1. Follow the prompts to complete the deployment.

Using Custom Domains

Most static hosting platforms support custom domains. Here’s how to set it up on some popular platforms:

Selfhosted/Server

1. Check your ip adress and make sure the correct port is exposed.
2. Point a A record to that ip adress.
3. Restart static website.

Netlify

1. Go to your site’s settings in the Netlify dashboard.
2. Navigate to the "Domain settings" section.
3. Add your custom domain and follow the instructions to configure DNS settings.

Vercel

1. Go to your project settings in the Vercel dashboard.
2. Navigate to the "Domains" section.
3. Add your custom domain and follow the instructions to configure DNS settings.

GitHub Pages

1. Go to your repository settings on GitHub.
2. Navigate to the "Pages" section.
3. Enter your custom domain in the provided field.
4. Configure your DNS settings as instructed.

Tips for Successful Hosting

• Ensure your output directory is included in your version control or deployment process.
• Regularly update your site by re-running the build command and redeploying.
• Use environment variables or configuration files to manage settings for different deployment environments.
• Monitor your site’s performance and optimize as needed.